feat(supervisor): advertise accepted application route installations - #4940

Summary

Persist validated, expiring evidence of application routes installed by supervisors. Integrate the shared-supervisor ownership authority merged in #4864 so dedicated and shared installations can be advertised safely.

Based on main at dbc0517a3.

Related Issue

Closes #4939. Part of RFC 0017.

Changes

• Preserve cleanup progress after each bounded record attempt so sweep timeouts or malformed/stalled records cannot starve later expired installations; retain conditional deletion to protect renewals.

• Resolve the trusted supervisor endpoint once per lease exchange, retaining session/runtime/ownership fencing, shared readiness checks, and absolute expiry.

• Resolve trusted application endpoints through the optional ComputeDriverAppEndpoints.ResolveSupervisorAppEndpoint extension RPC, independently of GetSandbox. The baseline ComputeDriver service and existing factories remain compatible. In-process factories register the optional resolver during build; unsupported drivers withhold publication; resolution failures cannot fail ordinary sandbox observations.

• Fence installation reports and discovery eligibility by runtime, configuration, session, credential epoch, current acknowledged pool owner, and process/member readiness.

• Resolve shared application endpoints from trusted Kubernetes membership and Pod state, independently of runtime control addresses.

• Revalidate durable authority before each serving lease; enforce absolute lease expiry and a shared listener serving-authority bound of at most 15 seconds, closing stale streams.

• Preserve workload identity across owner changes; keep gateway-session identity independent of supervisor takeover identity.

Application route advertisement flow

This PR records which application routes a supervisor has actually installed, together with a trusted endpoint and an expiry.

flowchart TB
    subgraph Supervisor["Supervisor — dedicated or shared"]
        Config["Apply sandbox service configuration"]
        Listener["Application listener<br/>Installed routes"]
        Report["Installation report<br/>Routes + configuration identity<br/>Session identity + lease sequence"]
        Config --> Listener
        Listener --> Report
    end

    subgraph Gateway["OpenShell gateway"]
        Session["Authenticated supervisor session<br/>App listener enabled + capability advertised"]
        Lease["Issue single-use lease challenge<br/>Every 5 seconds · expires within 15 seconds"]
        Validate["Validate report<br/>Current session, runtime and configuration<br/>Current ownership and readiness"]
        Resolve["ResolveSupervisorAppEndpoint<br/>Once per lease exchange"]
        Accept["Accept installation evidence<br/>Routes + trusted endpoint + expiry"]
        Window["Session-local lease window<br/>Trusted endpoint + sequence + expiry"]
        Session --> Resolve
        Resolve --> Lease
        Lease --> Window
        Window -->|"Reuse only for matching report"| Validate
        Validate --> Accept
    end

    Authority[("Shared ownership and membership state")]
    Driver["Kubernetes compute driver<br/>Resolve dedicated supervisor Pod IP<br/>or acknowledged shared owner's Pod IP"]
    Store[("Shared installation records<br/>One per sandbox<br/>Expiring, conditionally updated")]

    Lease -->|"Challenge over existing session"| Listener
    Report -->|"Response over existing session"| Validate
    Authority -->|"Fence stale owners and sessions"| Validate
    Resolve --> Driver
    Driver -->|"Trusted Pod IP + app port"| Resolve
    Accept --> Store

The supervisor reports what it installed; the compute driver determines where it can be reached. The gateway combines those only after validating current authority. Multiple gateway replicas use shared state to validate ownership. The driver endpoint is resolved before issuing each challenge and reused only for that challenge's response; acceptance still checks durable ownership and shared readiness. The next challenge resolves afresh, and reuse never extends the original expiry.

During shared-supervisor takeover, old evidence becomes ineligible. The replacement must install the configuration and report it before its endpoint can be published. Shared listeners also lose serving authority when their lease expires, closing stale application streams.

This PR supplies the evidence used by the later discovery API. It does not create ingress resources or carry application traffic through the gateway. Installation evidence does not establish application health or external ingress readiness.

Release Notes

Testing

• Rebased review fixes: all 3,465 combined-stack Rust library tests and eight proxy tests passed, including six new cleanup/lease-reuse regressions. Strict all-target Clippy, gateway/client compilation, formatting, affected-workflow Actionlint, and lockfile alignment passed. 39 PostgreSQL-dependent tests were ignored; no new live-cluster run was performed.

• 40 focused combined-stack Rust regression tests cover listener routing, route-limit concurrency, shutdown fencing, advertisements, discovery, and proxy behavior.

• Local k3d validated the Service removal with dedicated push/poll, abrupt shared-owner takeover, HTTP/WebSockets, network-policy denial, freshness/withdrawal, outage recovery, and disabled-listener gateway access. Workload identity and memory survived owner changes.

• Discovery API snapshots/watches and workspace-restricted discovery credentials drove two proxy replicas; both followed Pod-IP endpoints, graceful owner handover, and route withdrawal without per-sandbox app Services.

• Helm lint/unit/parser/coherence/scaling checks, Python lint/format/type checks, and topology assertions passed.

Live Kubernetes validation preceded integration of the latest listener hardening;
focused Rust regressions validate that final integration. New-head CI is pending.

Qualification limits

Live HA validation exercised supervisor process/Pod loss on a local k3d cluster. Whole-node failure, real network partitions, metric-driven HPA, sustained production load, and published release artifacts remain unqualified. Grant-file projection contributes to revocation propagation time. Main now includes #4842 for gateway-mediated hashed hostnames. Direct application-listener/discovery hostnames remain readable; extending hashed naming to that path and installation-status presentation (#4670) remain separate work.

The example Kubernetes HTTPRoute controller is a deferred compatibility POC outside this stack.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Relevant implementation, configuration, and API documentation updated

PR dependency order: #4940 → #4941 → #4956 → #4963 → #4964 → #4957.